<?php
	require "Persistence/cn.php";
	$DB=new softrDB('Persistence/queries.json','ejemplo01');	
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Capa de Acceso a Datos</title>
</head>

<body>
	<h1>softrDB</h1>
    <h2>Qué es?</h2>
    softrDB es una pequeña clase hecha en PHP para facilitar el acceso a base de datos. Funciona como una capa de persistencia.
    <h2>Cómo funciona?</h2>
    softrDB gestiona un archivo con extensión .json, ya que dicho archivo está escrito en esa notación. Ésta contiene en formato JSON todos los queries que se va a utilizar en una aplicación web PHP. Una vez instanceada la clase softrDB, se pueden ejecutar los métodos de la misma, y traer información de la base de datos. Además permite la utilización de argumentos, que es posible pasarle al query que se desea ejecutar del archivo con extensión JSON.
    <h2>Elementos que lo conforman</h2>
    <ul>
    	<li>cn.php<br />
        El archivo de configuración de softrDB y conexión con base de datos.</li>
        <li>JSON.php<br />
        Libreria desarrollada por <a href="http://json.org/" alt="JSON" title="JSON">http://json.org/</a>, que facilita el uso de estructuras JSON.</li>
        <li>softrDB.php<br />
        La clase con los métodos para la capa de persistencia.</li>
        <li>queries.php
        Archivo en notación JSON con los queries, clasificados en módulos, a utilizar en el proyecto.</li>
    </ul>
    <h2>Configuración</h2>
    <ol>
    	<li>En el archivo cn.php:<br />
            <ul>
                <li>Colocar la ruta donde se encuentran los archivos de la capa de Persistencia. Por default se verá $path='Persistence/', en donde 'Persistence/' es el valor que deberá cambiarse en caso de que los archivos sean ubicados en una carpeta distinta</li>
                <li>Colocar los datos de la base de datos.<br />
                $hostname = "localhost";
	$database = "ejemplo01";
	$username = "root";
	$password = "";</li>
            </ul>
        </li>
        <li>Colocar los queries el archivo queries.json . Deben tomarse en cuenta las siguientes consideraciones:<br />
        	<ul>
            	<li>Iniciar el archivo con '{' y terminar con '}' para indicar que utilizaremos notación JSON</li>
                <li>En primer término irán los nombres de los módulos en que se clasificaran los queries, éstos no van dentro de comillas simples ni dobles. Posteriormente, dentro de cada módulo los queries, que se compondrán de un ID con las mismas caracteristicas de los nombres de los módulos, seguidos de su valor que es propiamente el query.</li>
                <li>Dentro del query, se pueden poner argumentos, que serán sustituídos con los valores al llamar el método. La nomenclatura a utilizar es '?A' para el primer argumento, '?B' para el segundo, '?C' para el tercero, y así para cada letra del alfabeto. Se puede utilizar más de una vez un mismo argumento, es decir, ?A puede aparecer muchas veces en un mismo query, conservando el valor que se le haya mandado en un inicio.</li>
                <li>Ver el ejemplo para comprender lo anterior mejor: <br />
                	<small><pre>
{
	customer:{
		CUS_L01:'SELECT * FROM mcustomer;',
		CUS_L02:'SELECT * FROM mcustomer C INNER JOIN ccountry P ON C.cCou_ID=P.cCou_ID;',
		CUS_L03:'SELECT * FROM mcustomer limit 5;'
	},
	country:{
		COU_L01:'SELECT * FROM ccountry;',
		COU_L02:'SELECT * FROM ccountry WHERE cCou_Name like "%?A%";',
		COU_U01:'UPDATE ccountry SET cCou_Name="JAPON" WHERE cCou_ID=?A LIMIT 1;'
	}
}
                    </pre></small>
                    <br />
                    En este ejemplo, tenemos dos módulos: customer y country. cada uno de ellos tiene 3 queries. Se propone la nomenclatura para los nombres de identificación de los queries como sigue: NOM_NXX, donde "NOM" son 3 letras relacionadas con el nombre del módulo, "N" es una letra que nos indica qué tipo de query és (L=LOAD o SELECT, U=UPDATE, I=INSERT, D=DELETE), y "XX" es un número consecutivo. Estos nombre de ID de los queries se sugieren para mayor identificación, pero no tiene que ver con el funcionamiento de la clase. 
                </li>
            </ul>
        </li>
    </ol>
    <h2>Utilización</h2>
    <ul>
    	<li>Requerir el archivo cn.php: <strong>require "Persistence/cn.php";</strong></li>
        <li>Instancear la clase: <strong>$DB=new softrDB('Persistence/queries.json','ejemplo01');</strong><br />
        El primer parámetro es la ruta donde se encuentra el archivo de queries con extensión .json y el segundo argumento es opcional, en caso de que se quiera poner un identificador para poder hacer uso de más de un archivo de queries con extensión .json</li>
        <li>Ejecutar el query. <strong>$rsCustomers=$DB->loadQuery("customer","CUS_L01");</strong><br />
        El primer parámetro es el módulo en el que se clasificó los queries, y el segundo argumento es el nombre del query a ejecutar.</li>
        <li><strong>$rsCustomers</strong> en el punto anterior, es una variable que recibirá un arreglo con los datos que haya regresado el query. Esto es sólo en el caso de un SELECT, para los casos de UPDATE, INSERT o DELETE, no se requiere asignar a una variable. basta con <strong>$DB->loadQuery("country","COU_U01");</strong>. En el caso de SELECT, una vez asignado a una variable, ésta recibirá un arreglo con todos los datos devueltos por el query.
        <p />Si ejecutamos $rsCustomers=$DB->loadQuery("customer","CUS_L01");, ahora $rsCustomers será un arreglo con la información de la tabla mcustomer, y si lo recorremos así<br />
        <pre>
&lt;?php 
	$rsCustomers=$DB->loadQuery("customer","CUS_L01");
	foreach($rsCustomers as $item){?>
		nombre: &lt;strong>&lt;?=$item['mCus_Name'];?>&lt;/strong><br />
&lt;?php }?>
        </pre>
        Obtendremos:
        <p />
        <?php 
			$rsCustomers=$DB->loadQuery("customer","CUS_L01");
			foreach($rsCustomers as $item){?>
				nombre: <strong><?=$item['mCus_Name'];?></strong><br />
		<?php }?>
        </li>
    </ul>
    <h2>Métodos de la clase</h2>
    <ul>
    	<li>$DB->loadQuery("mod","query","parametro1|parametro2|parametro3")<br />
        Ejecuta un query. El primer argumento es el módulo del query, el segundo el ID del query a ejecutar, y el tercero los argumentos, los cuales se enviarán separados por el caracter PIPE "|". Ejemplo: $DB->loadQuery("country","COU_U01","2"). Al llamar a COU_U01 se referirá a 'UPDATE ccountry SET cCou_Name="JAPON" WHERE cCou_ID=?A;', y al sustituir el parámetro enviado quedará como 'UPDATE ccountry SET cCou_Name="JAPON" WHERE cCou_ID=2;'</li>
        <li>$DB->outQuery()<br />
        Función para ayuda de debug. Imprime el query formado en pantalla. Útil sobre todo en el uso de parámetros. Si ejecutamos COU_L02 de country, al usar $DB->outQuery() tendremos:<br />
        <small>
        <?php
			$rsCustomers=$DB->loadQuery("country","COU_L02","niq");
			$DB->outQuery();
		?>
        </small>
        </li>
        <li>$DB->outResultSet()<br />
        Función para ayuda de debug. Imprime todo el resultset en pantalla. Útil sobre todo en el uso de parámetros. Por ejemplo, si ejecutamos CUS_L01 de customer, su outResultSet será:<br />
        <small>
        <?php 
			$rsCustomers=$DB->loadQuery("customer","CUS_L01");
			$DB->outResultSet();
		?></li>
        </small>
    </ul>
    <h2>Descarga</h2>
    softrDB, ejemplos y script de BD de ejemplo
    
    <h2>Ejemplos (para verse en el código php)</h2>
    <table>
    	<caption>clientes con país</caption>
        <thead><tr><th>Cliente</th><th>País</th></tr></thead>
        <tbody>
    <?php
		$rsCustomers=$DB->loadQuery("customer","CUS_L02");
		foreach($rsCustomers as $item){?>
				<tr><td><?=$item['mCus_Name'];?></td><td><?=$item['cCou_Name'];?></td></tr>
		<?php }?>
        </tbody>
    </table>
    <br />
     <table>
    	<caption>Primeros 5 clientes</caption>
        <thead><tr><th>Cliente</th></tr></thead>
        <tbody>
    <?php
		$rsCustomers=$DB->loadQuery("customer","CUS_L03");
		foreach($rsCustomers as $item){?>
				<tr><td><?=$item['mCus_Name'];?></td></tr>
		<?php }?>
        </tbody>
    </table>
    <br />
    <table>
    	<caption>Primeros N clientes, por parámetro(3)</caption>
        <thead><tr><th>Cliente</th><th>País</th></tr></thead>
        <tbody>
    <?php
		$rsCustomers=$DB->loadQuery("customer","CUS_L04","3");
		foreach($rsCustomers as $item){?>
				<tr><td><?=$item['mCus_Name'];?></td><td><?=$item['cCou_Name'];?></td></tr>
		<?php }?>
        </tbody>
    </table>
    <br />
     <table>
    	<caption>Países que lleven la frase "na"</caption>
        <thead><tr><th>id</th><th>País</th></tr></thead>
        <tbody>
    <?php
		$rsCustomers=$DB->loadQuery("country","COU_L02","na");
		foreach($rsCustomers as $item){?>
				<tr><td><?=$item['cCou_ID'];?></td><td><?=$item['cCou_Name'];?></td></tr>
		<?php } ?>
        </tbody>
    </table>
</body>
</html>
